Scripted Rules

In this section:

About Scripted Rules

Scripted rules allow custom rules to be created using Windows PowerShell or VB Scripts. The success or failure of the Script determines whether the security level, Allowed Items, and Denied Items that are part of the rule apply to the user.

Scripted rules can take advantage of any interface accessible via PowerShell or VBScript, such as COM (Component Object Model).

Each script is evaluated under the following circumstances:

  • When a new configuration is deployed to the computer.
  • When a user logs on.

To create or edit scripts go to the required Scripted Rule Set in the Application Control Configuration Editor. Rule Sets > Scripted > [Rule Set name]

You can define when the script is to be run using the following Scripted Rule Options:

  • Run script:
    • Per session as user - The script runs for each user logging on. Settings are only applied for the duration of the user session.
    • Per session as SYSTEM - The script runs with SYSTEM account permissions once for each user logging on. Settings are only applied for the duration of the user session.
    • Per computer as SYSTEM - The script runs with SYSTEM account permission once at computer startup. Settings are applied to all user sessions until the computer restarts, the Application Control agent restarts or there is a configuration change.

    Caution: Running scripts as the SYSTEM user can cause serious damage to your computer and should only be enabled by experienced script authors.

  • Wait for logon to complete - Select to prevent the script from running until user logon is complete.

VBScripts

Each script is run within a hosted script engine allowing greater control over the script execution whilst providing a high degree of input and output control.

  • No VBS file is used.
  • No separate process is spawned.

A script must be written as a function and can contain many functions, but a main start function must be specified. The start function is run by the Application Control agent and can be used to call other functions.

The AMScriptRule COM object is built into the scripting engine and provides access to the following methods:

  • strUsername = AMScriptRule.UserName
  • strUserdomain = AMScriptRule.UserDomain
  • strSessionid = AMScriptRule.SessionID
  • strStationname = AMScriptRule.WinStation

    The Microsoft standard in this instance means that WinStation returns the value of the name of the Terminal Services Session, which is determined by the type of session with typical values being ’Console’ or ’RDP-Tcp#34’, instead of the Window Station name which is typically WinSta0.

The AMScriptRule COM object also includes the following methods:

  • strLog = AMScriptRule.Log "My Log Statement"

    Allows you to output logging strings to the agent log file for use with debugging scripted rules.

  • strEnvironmentvar = AMScriptRule.ExpandEnvironment ("%MyEnvironmentVariables%")

    Expands environment variables of the user running the script.

Using WScript. shell to expand environment variables only returns SYSTEM variables.

Windows PowerShell Scripts

If the script returns (exits) with a value of 0, the script will pass and the rules are applied. If any non-zero value is returned, the script will fail and the rules will not apply.

Each PowerShell script is executed in an instance of PowerShell.exe and as such Application Control neither enforces nor adds any specific syntax – all correctly formed PowerShell will work.

PowerShell must be installed on any endpoints that will be using the script.

Sample scripts

The following VBScript demonstrates how to control the applications to which a user has access.

Copy 
Function ScriptedRule()
’Name of Filter scan expected to pass
ExpectedFilter = "FWALL"
’Get Server Name
Set objNTinfo = CreateObject ("WinNTSystemInfo")
ServerName = lcase (objNTInfo.ComputerName)
’Set initial return value
ScriptedRule = False
’Create MetaFrame Session Object
Set MFSession = Createobject ("MetaFrameCOM.MetaFrameSession")
’Initialize the session filters for this session
For Each x in MFSession.SmartAccessFilters
’return true if our filter is found
If x = ExpectedFilter Then
ScriptedRule=True
AMScriptRule.Log "SmartAccessFilter match found."
End If
Next
End Function 

The following VBScript can be used to determine if a computer is in a Computer Organizational Unit:

Copy 
Function ScriptedRule()
ScriptedRule = vbFalse
strCompName = AMScriptRule.StationName
Set oRootDSE = GetObject("LDAP://RootDSE")
strDNSDomain = oRootDSE.Get("DefaultNamingContext")
Set oOU = GetObject("LDAP://OU=TheOUyouAreSearching,OU=Parent,OU=Parent," & strDNSDomain)
oOU.GetInfo
For each member in oOU
    If UCase(strCompName) = UCase(member.CN) Then
        ScriptedRule = vbTrue
        Exit For
    End If
Next
End Function

The following sample VBScript shows the main components of a script and demonstrates how to access information about the username of the user logging on to the system, and match with a specific domain and organizational unit:

Copy 
Function MyScript()
'Get the username of the user logging in (also works when running as SYSTEM)
strUserName = AMScriptRule.UserName
'Get the domain of the user logging in (also works when running as SYSTEM)
strUserDomain = AMScriptRule.UserDomain
'Look up user environment variables (when running as SYSTEM, only SYSTEM variables are available)
strClientName = AMScriptRule.ExpandEnvironment ("%ClientName%")
'Log the output
AMScriptRule.Log strUserName & " logged in on " & strClientName
'Check if the user is a member of the domain
If strUserdomain = "MyDomain" Then
'If so, see if the user is in the MyOU OU
Set objOU = GetObject ("LDAP://ou=MyOU,dc=MyDomain,dc=com")
objOU.Filter = Array("user")
For Each objUser In objOU
'Check if there is a match with the user logging on
If objUser.sAMAccountName = strUserName Then
'if there is, then set the function to True
MyScript = True
End If
Next
End If
'Unless there is a username match, the function defaults to False
End Function

The following sample Windows PowerShell script shows the main components of a script and demonstrates how to access information about the username of the user logging on to the system, and match with a specific domain and organizational unit:

Copy 
#Script checks if the current user is a member of the OU specified
# Return 0 if TRUE
# 1 otherwise
$logonuser = $env:username
$bindpt = [adsi] "LDAP://OU=TS_Users,OU=Users,OU=MyUser,OU=MyOU,DC=MyDomain,DC=com"
$users = New-Object System.DirectoryServices.DirectorySearcher $bindpt
$users.Filter = "(&(objectClass=User)(sAMAccountName=$logonuser))"
$obj = $users.FindOne()
if($obj -eq $null)
{
#" Not a Member"
exit 1
}

Related Topics

Rule Sets

Rule Collections